Configuring HashiCorp Vault
To set up Vault using a ProtectServer 3 HSM, complete the steps described in this section.
Enabling the PKCS#11 Seal
The PKCS#11 seal configures Vault to use a ProtectServer 3 HSM with PKCS#11 as the seal wrapping mechanism.
To enable the PKCS#11 Seal
-
Create a configuration file for Vault named "config.json" and specify the
seal
,storage
, andlistener
stanzas.-
lib
is the path to the PKCS#11 library shared object file. -
slot
is the HSM partition slot number. -
pin
is the HSM partition password. -
hmac_key_label
is the label of the key to use for HMACing. -
Generate key
instructs Vault to generate a key if no existing key with the label specified by key label can be found at Vault initialization time.
Note
Alternatively, the HSM seal can be activated by providing the following environment variables:
-
VAULT_HSM_LIB
-
VAULT_HSM_SLOT
-
VAULT_HSM_PIN
-
VAULT_HSM_KEY_LABEL
-
VAULT_HSM_HMAC_KEY_LABEL
-
VAULT_HSM_GENERATE_KEY
Although the configuration file allows you to pass in VAULT_HSM_PIN as part of the seal's parameters, it is strongly recommended to set this value via environment variables.
-
Configuring Entropy Augmentation
Vault Enterprise version 1.3 introduced the entropy augmentation function to leverage an HSM for augmenting system entropy via the PKCS#11 protocol.
To configure entropy augmentation, define the entropy
stanza in config.json.
Note
Since Vault will delegate random number generation to the HSM, be sure to set the seal
stanza with HSM cluster connection information.
Starting Vault
After enabling the PKCS#11 seal and configuring entropy augmentation, start the Vault server using config.json.
Initializing Vault
You must initialize Vault before accessing it.
When Vault is initialized while using an HSM, recovery keys are returned to the operator instead of unseal keys. Some Vault operations, such as root token generation, will require these recovery keys.
To initialize Vault
-
Launch a new terminal session and run the following command:
Note
Vault must continue running in the first terminal while you complete the remaining steps of this integration.
-
Check the status of Vault.
-
Initialize Vault.
The preceding command will generate a recovery key and initial root token. Copy these keys and secure them.
Note the following logs in the first terminal where the Vault server is running:
-
Verify the keys generated on the slot.
Logging In to Vault
You must log on to Vault to begin configuring and managing the secrets engine.
To log on to the Vault
-
Log on to Vault.
<VAULT-TOKEN>
is the initial root token generated during Vault initialization. -
Verify that the Vault server is initialized and auto-unsealed.
-
If the UI has been enabled in config.json, access the Vault UI at http://127.0.0.1:8200/ui
Input the VAULT TOKEN in the Token field to log on.
Using the Secrets Engine
Secrets engines are components that store, generate, or encrypt data. The KV secrets engine is used to store arbitrary secrets within the configured physical storage for Vault. Versioning can be enabled and a configurable number of versions for each key will be stored.
To use the secrets engine
Enabling Entropy Augmentation
To leverage the external entropy source, set the external_entropy_access
parameter to true
while enabling a secrets
engine or auth
method.
To enable the external entropy source on a transit secrets engine
-
Enable
transit
secrets engine with the external entropy source. -
List the enabled secrets engine with the
-detailed
flag.External Entropy Access is set to true for transit.
-
Use the transit secrets engine to encrypt sensitive data that leverages the HSM as its external entropy source, and create a new encryption key named "orders".
-
Send a base64-encoded string to be encrypted by Vault.
-
Verify that the ciphertext can be decrypted.
-
Decode to get the original plaintext string.
Note
Connectivity to the HSM is required when external entropy access is enabled. If the HSM becomes unreachable, the transit secrets engine returns an error and data cannot be encrypted or decrypted until connection to the HSM is restored.
This completes the integration of HashiCorp Vault with a ProtectServer 3 HSM.